/*******************************************************************************
* Copyright (c) 2000, 2015 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.ui;
import org.eclipse.core.runtime.content.IContentType;
import org.eclipse.jface.resource.ImageDescriptor;
/**
* Registry of editors known to the workbench.
* <p>
* An editor can be created in one of two ways:
* <ul>
* <li>An editor can be defined by an extension to the workbench.</li>
* <li>The user manually associates an editor with a given resource extension
* type. This will override any default workbench or platform association.
* </li>
* </ul>
* </p>
* <p>
* The registry does not keep track of editors that are "implicitly" determined.
* For example a bitmap (<code>.bmp</code>) file will typically not have a
* registered editor. Instead, when no registered editor is found, the
* underlying OS is consulted.
* </p>
* <p>
* This interface is not intended to be implemented by clients.
* </p>
*
* @see org.eclipse.ui.IWorkbench#getEditorRegistry()
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface IEditorRegistry {
/**
* The property identifier for the contents of this registry.
*/
public static final int PROP_CONTENTS = 0x01;
/**
* The identifier for the system external editor descriptor. This descriptor
* is always present in the registry on all platforms.
* This editor requires an input which implements
* {@link org.eclipse.ui.IPathEditorInput IPathEditorInput}.
* Use {@link #findEditor findEditor} to access the editor descriptor for
* this identifier.
*
* @since 3.0
*/
public static final String SYSTEM_EXTERNAL_EDITOR_ID = "org.eclipse.ui.systemExternalEditor"; //$NON-NLS-1$
/**
* The identifier for the system in-place editor descriptor. This descriptor
* is only present in the registry on platforms that support in-place editing
* (for example Win32). This editor requires an input which implements
* {@link org.eclipse.ui.IInPlaceEditorInput IInPlaceEditorInput}. Use
* {@link #findEditor findEditor} to access the editor descriptor for this
* identifier.
*
* @since 3.0
*/
public static final String SYSTEM_INPLACE_EDITOR_ID = "org.eclipse.ui.systemInPlaceEditor"; //$NON-NLS-1$
/**
* Adds a listener for changes to properties of this registry.
* Has no effect if an identical listener is already registered.
* <p>
* The properties ids are as follows:
* <ul>
* <li><code>PROP_CONTENTS</code>: Triggered when the file editor mappings in
* the editor registry change.</li>
* </ul>
* </p>
*
* @param listener a property listener
*/
public void addPropertyListener(IPropertyListener listener);
/**
* Finds and returns the descriptor of the editor with the given editor id.
*
* @param editorId the editor id
* @return the editor descriptor with the given id, or <code>null</code> if not
* found
*/
public IEditorDescriptor findEditor(String editorId);
/**
* Returns the default editor. The default editor always exist.
*
* @return the descriptor of the default editor
* @deprecated The system external editor is the default editor.
* Use <code>findEditor(IEditorRegistry.SYSTEM_EXTERNAL_EDITOR_ID)</code>
* instead.
*/
@Deprecated
public IEditorDescriptor getDefaultEditor();
/**
* Returns the default editor for a given file name. This method assumes an
* unknown content type for the given file.
* <p>
* The default editor is determined by taking the file extension for the
* file and obtaining the default editor for that extension.
* </p>
*
* @param fileName
* the file name in the system
* @return the descriptor of the default editor, or <code>null</code> if
* not found
*/
public IEditorDescriptor getDefaultEditor(String fileName);
/**
* Returns the default editor for a given file name and with the given content type.
* <p>
* The default editor is determined by taking the file extension for the
* file and obtaining the default editor for that extension.
* </p>
*
* @param fileName the file name in the system
* @param contentType the content type or <code>null</code> for the unknown content type
* @return the descriptor of the default editor, or <code>null</code> if not
* found
* @since 3.1
*/
public IEditorDescriptor getDefaultEditor(String fileName, IContentType contentType);
/**
* Returns the list of file editors registered to work against the file with
* the given file name. This method assumes an unknown content type for the
* given file.
* <p>
* Note: Use <code>getDefaultEditor(String)</code> if you only the need
* the default editor rather than all candidate editors.
* </p>
*
* @param fileName
* the file name in the system
* @return a list of editor descriptors
*/
public IEditorDescriptor[] getEditors(String fileName);
/**
* Returns the list of file editors registered to work against the file with
* the given file name and with the given content type.
* <p>
* Note: Use <code>getDefaultEditor(String)</code> if you only the need
* the default editor rather than all candidate editors.
* </p>
*
* @param fileName
* the file name in the system
* @param contentType
* the content type or <code>null</code> for the unknown
* content type
* @return a list of editor descriptors
* @since 3.1
*/
public IEditorDescriptor[] getEditors(String fileName, IContentType contentType);
/**
* Returns a list of mappings from file type to editor. The resulting list
* is sorted in ascending order by file extension.
* <p>
* Each mapping defines an extension and the set of editors that are
* available for that type. The set of editors includes those registered
* via plug-ins and those explicitly associated with a type by the user
* in the workbench preference pages.
* </p>
*
* @return a list of mappings sorted alphabetically by extension
*/
public IFileEditorMapping[] getFileEditorMappings();
/**
* Returns the image descriptor associated with a given file. This image is
* usually displayed next to the given file. This method assumes an unknown
* content type for the given file.
* <p>
* The image is determined by taking the file extension of the file and
* obtaining the image for the default editor associated with that
* extension. A default image is returned if no default editor is available.
* </p>
*
* @param filename
* the file name in the system
* @return the descriptor of the image to display next to the file
*/
public ImageDescriptor getImageDescriptor(String filename);
/**
* Returns the image descriptor associated with a given file. This image is
* usually displayed next to the given file.
* <p>
* The image is determined by taking the file extension of the file and
* obtaining the image for the default editor associated with that
* extension. A default image is returned if no default editor is available.
* </p>
*
* @param filename
* the file name in the system
* @param contentType
* the content type of the file or <code>null</code> for the
* unknown content type
* @return the descriptor of the image to display next to the file
* @since 3.1
*/
public ImageDescriptor getImageDescriptor(String filename, IContentType contentType);
/**
* Removes the given property listener from this registry. Has no effect if
* an identical listener is not registered.
*
* @param listener
* a property listener
*/
public void removePropertyListener(IPropertyListener listener);
/**
* Sets the default editor id for the files that match that
* specified file name or extension. The specified editor must be
* defined as an editor for that file name or extension.
*
* @param fileNameOrExtension the file name or extension pattern (e.g. "*.xml");
* @param editorId the editor id or <code>null</code> for no default
*/
public void setDefaultEditor(String fileNameOrExtension, String editorId);
/**
* Returns whether there is an in-place editor that could handle a file
* with the given name.
*
* @param filename the file name
* @return <code>true</code> if an in-place editor is available, and
* <code>false</code> otherwise
* @since 3.0
*/
public boolean isSystemInPlaceEditorAvailable(String filename);
/**
* Returns whether the system has an editor that could handle a file
* with the given name.
*
* @param filename the file name
* @return <code>true</code> if an external editor available, and
* <code>false</code> otherwise
* @since 3.0
*/
public boolean isSystemExternalEditorAvailable(String filename);
/**
* Returns the image descriptor associated with the system editor that
* would be used to edit this file externally.
*
* @param filename the file name
* @return the descriptor of the external editor image, or <code>null</code>
* if none
* @since 3.0
*/
public ImageDescriptor getSystemExternalEditorImageDescriptor(
String filename);
}